home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / perl5 / Scope / Guard.pm
Encoding:
Perl POD Document  |  2010-05-16  |  3.7 KB  |  184 lines
  1. package Scope::Guard;
  2.  
  3. use strict;
  4. use warnings;
  5.  
  6. use Carp qw(confess);
  7. use Exporter ();
  8.  
  9. our @ISA = qw(Exporter);
  10. our @EXPORT_OK = qw(guard scope_guard);
  11. our $VERSION = '0.20';
  12.  
  13. sub new {
  14.     confess "Can't create a Scope::Guard in void context" unless (defined wantarray);
  15.  
  16.     my $class = shift;
  17.     my $handler = shift() || die 'Scope::Guard::new: no handler supplied';
  18.     my $ref = ref $handler || '';
  19.  
  20.     die "Scope::Guard::new: invalid handler - expected CODE ref, got: '$ref'"
  21.         unless (UNIVERSAL::isa($handler, 'CODE'));
  22.  
  23.     bless [ 0, $handler ], ref $class || $class;
  24. }
  25.  
  26. sub dismiss {
  27.     my $self = shift;
  28.     my $dismiss = @_ ? shift : 1;
  29.  
  30.     $self->[0] = $dismiss;
  31. }
  32.  
  33. sub guard(&) { __PACKAGE__->new(shift) }
  34. sub scope_guard($) { __PACKAGE__->new(shift) }
  35.  
  36. sub DESTROY {
  37.     my $self = shift;
  38.     my ($dismiss, $handler) = @$self;
  39.  
  40.     $handler->() unless ($dismiss);
  41. }
  42.  
  43. 1;
  44.  
  45. __END__
  46.  
  47. =pod
  48.  
  49. =head1 NAME
  50.  
  51. Scope::Guard - lexically-scoped resource management
  52.  
  53. =head1 SYNOPSIS
  54.  
  55.     my $guard = guard { ... };
  56.  
  57.       # or
  58.  
  59.     my $guard = scope_guard \&handler;
  60.  
  61.       # or
  62.  
  63.     my $guard = Scope::Guard->new(sub { ... });
  64.  
  65.     $guard->dismiss(); # disable the handler
  66.  
  67. =head1 DESCRIPTION
  68.  
  69. This module provides a convenient way to perform cleanup or other forms of resource
  70. management at the end of a scope. It is particularly useful when dealing with exceptions:
  71. the C<Scope::Guard> constructor takes a reference to a subroutine that is guaranteed to
  72. be called even if the thread of execution is aborted prematurely. This effectively allows
  73. lexically-scoped "promises" to be made that are automatically honoured by perl's garbage
  74. collector.
  75.  
  76. For more information, see: L<http://www.drdobbs.com/cpp/184403758>
  77.  
  78. =head1 METHODS
  79.  
  80. =head2 new
  81.  
  82.     my $guard = Scope::Guard->new(sub { ... });
  83.  
  84.       # or
  85.  
  86.     my $guard = Scope::Guard->new(\&handler);
  87.  
  88. The C<new> method creates a new C<Scope::Guard> object which calls the supplied handler when its C<DESTROY> method is
  89. called, typically at the end of the scope.
  90.  
  91. =head2 dismiss
  92.  
  93.     $guard->dismiss();
  94.  
  95.       # or
  96.  
  97.     $guard->dismiss(1);
  98.  
  99. C<dismiss> detaches the handler from the C<Scope::Guard> object. This revokes the "promise" to call the
  100. handler when the object is destroyed.
  101.  
  102. The handler can be re-enabled by calling:
  103.  
  104.     $guard->dismiss(0);
  105.  
  106. =head1 EXPORTS
  107.  
  108. =head2 guard
  109.  
  110. C<guard> takes a block and returns a new C<Scope::Guard> object. It can be used
  111. as a shorthand for:
  112.  
  113.     Scope::Guard->new(...)
  114.  
  115. e.g.
  116.  
  117.     my $guard = guard { ... };
  118.     
  119. Note: calling C<guard> anonymously, i.e. in void context, will raise an exception.
  120. This is because anonymous guards are destroyed B<immediately>
  121. (rather than at the end of the scope), which is unlikely to be the desired behaviour.
  122.  
  123. =head2 scope_guard
  124.  
  125. C<scope_guard> is the same as C<guard>, but it takes a code ref rather than a block.
  126. e.g.
  127.  
  128.     my $guard = scope_guard \&handler;
  129.  
  130. or:
  131.  
  132.     my $guard = scope_guard sub { ... };
  133.  
  134. or:
  135.  
  136.     my $guard = scope_guard $handler;
  137.  
  138. As with C<guard>, calling C<scope_guard> in void context will raise an exception.
  139.  
  140. =head1 VERSION
  141.  
  142. 0.20
  143.  
  144. =head1 SEE ALSO
  145.  
  146. =over
  147.  
  148. =item * L<B::Hooks::EndOfScope|B::Hooks::EndOfScope>
  149.  
  150. =item * L<End|End>
  151.  
  152. =item * L<Guard|Guard>
  153.  
  154. =item * L<Hook::Scope|Hook::Scope>
  155.  
  156. =item * L<Object::Destroyer|Object::Destroyer>
  157.  
  158. =item * L<Perl::AtEndOfScope|Perl::AtEndOfScope>
  159.  
  160. =item * L<ReleaseAction|ReleaseAction>
  161.  
  162. =item * L<Scope::local_OnExit|Scope::local_OnExit>
  163.  
  164. =item * L<Scope::OnExit|Scope::OnExit>
  165.  
  166. =item * L<Sub::ScopeFinalizer|Sub::ScopeFinalizer>
  167.  
  168. =item * L<Value::Canary|Value::Canary>
  169.  
  170. =back
  171.  
  172. =head1 AUTHOR
  173.  
  174. chocolateboy <chocolate@cpan.org>
  175.  
  176. =head1 COPYRIGHT
  177.  
  178. Copyright (c) 2005-2010, chocolateboy.
  179.  
  180. This module is free software. It may be used, redistributed and/or modified under the same terms
  181. as Perl itself.
  182.  
  183. =cut
  184.